openapi: 3.1.0
info:
  title: Coupa Core Invoices Requisitions API
  description: The primary RESTful API for accessing and managing core Coupa Business Spend Management (BSM) resources including purchase orders, invoices, requisitions, and suppliers. Supports both JSON and XML response formats. All endpoints require OAuth 2.0 or API key authentication. Coupa recommends using query parameters to limit result sets for optimal performance.
  version: 1.0.0
  termsOfService: https://www.coupa.com/company/trust/agreements
  contact:
    name: Coupa Support
    url: https://compass.coupa.com/en-us/support
  license:
    name: Proprietary
    url: https://www.coupa.com/company/trust/agreements
  x-logo:
    url: https://www.coupa.com/wp-content/themes/coupa/images/coupa-logo.svg
    altText: Coupa
servers:
- url: https://{instance}.coupahost.com/api
  description: Coupa Production Instance
  variables:
    instance:
      default: your-instance
      description: Your Coupa instance subdomain
security:
- oauth2: []
- apiKey: []
tags:
- name: Requisitions
  description: Create, retrieve, update, and manage requisitions. Requisitions are internal requests to purchase goods or services that go through approval workflows before becoming purchase orders.
  externalDocs:
    url: https://compass.coupa.com/en-us/products/product-documentation/integration-technical-documentation/the-coupa-core-api/resources/transactional-resources/requisitions-api-(requisitions)
paths:
  /requisitions:
    get:
      operationId: listRequisitions
      summary: Coupa List requisitions
      description: Retrieve a list of requisitions. Use query parameters to filter results. Supports filtering by status, requester, date ranges, and export status.
      tags:
      - Requisitions
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/returnObjectParam'
      - $ref: '#/components/parameters/dirParam'
      - name: status
        in: query
        description: Filter by requisition status (draft, cart, pending_buyer_action, pending_approval, approved, ordered, partially_received, received, abandoned, withdrawn)
        schema:
          type: string
          enum:
          - draft
          - cart
          - pending_buyer_action
          - pending_approval
          - approved
          - ordered
          - partially_received
          - received
          - abandoned
          - withdrawn
      - name: requester[login]
        in: query
        description: Filter by requester login
        schema:
          type: string
      - name: updated-at[gt]
        in: query
        description: Filter for records updated after this datetime
        schema:
          type: string
          format: date-time
      - name: exported
        in: query
        description: Filter by export status
        schema:
          type: boolean
      responses:
        '200':
          description: A list of requisitions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Requisition'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Requisition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createRequisition
      summary: Coupa Create a requisition
      description: Create a new requisition. Requires at least one requisition line. Line numbers must increment by one; duplicate line numbers are ignored. Currencies and users must have active status.
      tags:
      - Requisitions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequisitionCreate'
          application/xml:
            schema:
              $ref: '#/components/schemas/RequisitionCreate'
      responses:
        '201':
          description: Requisition created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /requisitions/{id}:
    get:
      operationId: getRequisition
      summary: Coupa Get a requisition
      description: Retrieve a single requisition by its Coupa internal ID.
      tags:
      - Requisitions
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/returnObjectParam'
      responses:
        '200':
          description: A single requisition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateRequisition
      summary: Coupa Update a requisition
      description: Update an existing requisition by its Coupa internal ID.
      tags:
      - Requisitions
      parameters:
      - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequisitionUpdate'
          application/xml:
            schema:
              $ref: '#/components/schemas/RequisitionUpdate'
      responses:
        '200':
          description: Requisition updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteRequisition
      summary: Coupa Delete a requisition
      description: Delete an existing requisition by its Coupa internal ID. Only requisitions in draft status can be deleted.
      tags:
      - Requisitions
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Requisition deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /requisitions/submit_for_approval:
    post:
      operationId: submitRequisitionForApproval
      summary: Coupa Submit a requisition for approval
      description: Submit a requisition for approval. The requisition must have at least one line item and valid accounting allocations.
      tags:
      - Requisitions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: The ID of the requisition to submit
      responses:
        '200':
          description: Requisition submitted for approval
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /requisitions/{id}/update_and_submit_for_approval:
    put:
      operationId: updateAndSubmitRequisition
      summary: Coupa Update and submit a requisition for approval
      description: Update a requisition and submit it for approval in a single operation.
      tags:
      - Requisitions
      parameters:
      - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequisitionUpdate'
      responses:
        '200':
          description: Requisition updated and submitted for approval
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ApprovalReference:
      type: object
      description: Reference to an approval record
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the approval
        status:
          type: string
          description: Approval status
    UserReference:
      type: object
      description: Reference to a Coupa user
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the user
        login:
          type: string
          description: User login name
        email:
          type: string
          format: email
          description: User email address
    SupplierReference:
      type: object
      description: Reference to a supplier
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the supplier
        name:
          type: string
          description: Supplier name
        number:
          type: string
          description: Supplier number
    CurrencyReference:
      type: object
      description: Reference to a currency
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the currency
        code:
          type: string
          description: ISO 4217 currency code
          example: USD
    Requisition:
      type: object
      description: A requisition representing an internal request to purchase goods or services, subject to approval workflows.
      properties:
        id:
          type: integer
          description: Coupa unique identifier
          readOnly: true
        req_title:
          type: string
          description: Optional title of the requisition
          maxLength: 50
        status:
          type: string
          description: Current requisition status
          enum:
          - draft
          - cart
          - pending_buyer_action
          - pending_approval
          - approved
          - ordered
          - partially_received
          - received
          - abandoned
          - backgrounded
          - withdrawn
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        total:
          type: number
          format: decimal
          description: Total amount in the requisition currency
          readOnly: true
        mobile-total:
          type: number
          format: decimal
          description: Total in mobile currency
          readOnly: true
        mobile-currency:
          type: string
          description: Default mobile currency code
        line-count:
          type: integer
          description: Number of lines in the requisition
          readOnly: true
        requester:
          $ref: '#/components/schemas/UserReference'
        requested-by:
          $ref: '#/components/schemas/UserReference'
        department:
          $ref: '#/components/schemas/DepartmentReference'
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          description: Ship to address attention
          maxLength: 255
        need-by-date:
          type: string
          format: date-time
          description: Date the items are needed by
        justification:
          type: string
          description: Requisition justification comments
        buyer-note:
          type: string
          description: Comments or notes from the buyer
        external-po-reference:
          type: string
          description: External PO reference that overrides auto-generated PO numbers
          maxLength: 255
        hide-price:
          type: boolean
          description: Whether to hide price from the supplier
        price-hidden:
          type: boolean
          description: Whether pricing is hidden from the supplier
        receiving-warehouse-id:
          type: integer
          description: Receiving warehouse ID
        requisition-lines:
          type: array
          description: Collection of requisition line items
          items:
            $ref: '#/components/schemas/RequisitionLine'
        approvals:
          type: array
          description: Approval workflow records
          items:
            $ref: '#/components/schemas/ApprovalReference'
          readOnly: true
        current-approval:
          $ref: '#/components/schemas/ApprovalReference'
        approver:
          $ref: '#/components/schemas/UserReference'
        pcard:
          type: object
          description: Purchasing card reference
          properties:
            id:
              type: integer
            name:
              type: string
        submitted-at:
          type: string
          format: date-time
          description: When the requisition was submitted
          readOnly: true
        reject-reason-comment:
          type: string
          description: Last rejection reason comment
          readOnly: true
        exported:
          type: boolean
          description: Whether the requisition has been exported
        last-exported-at:
          type: string
          format: date-time
          description: When the requisition was last exported
          readOnly: true
        tags:
          type: array
          description: Associated tags
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
        created-at:
          type: string
          format: date-time
          description: Timestamp when the requisition was created
          readOnly: true
        updated-at:
          type: string
          format: date-time
          description: Timestamp when the requisition was last updated
          readOnly: true
        created-by:
          $ref: '#/components/schemas/UserReference'
        updated-by:
          $ref: '#/components/schemas/UserReference'
    RequisitionLine:
      type: object
      description: A line item on a requisition
      properties:
        id:
          type: integer
          description: Coupa unique identifier
          readOnly: true
        line-num:
          type: integer
          description: Line number (must increment by one)
        description:
          type: string
          description: Item description
          maxLength: 255
        quantity:
          type: number
          format: decimal
          description: Quantity requested
        unit-price:
          type: number
          format: decimal
          description: Unit price (overrides preferred supplier pricing if item ID provided)
        total:
          type: number
          format: decimal
          description: Line total
          readOnly: true
        uom:
          type: object
          description: Unit of measure
          properties:
            id:
              type: integer
            code:
              type: string
        need-by-date:
          type: string
          format: date-time
          description: Date the item is needed by
        source-part-num:
          type: string
          description: Supplier part number
        supplier:
          $ref: '#/components/schemas/SupplierReference'
        commodity:
          type: object
          description: Commodity classification
          properties:
            id:
              type: integer
            name:
              type: string
        account:
          type: object
          description: Chart of accounts reference
          properties:
            id:
              type: integer
            code:
              type: string
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        item:
          type: object
          description: Catalog item reference
          properties:
            id:
              type: integer
            name:
              type: string
        contract:
          type: object
          description: Contract reference for this line
          properties:
            id:
              type: integer
            name:
              type: string
        created-at:
          type: string
          format: date-time
          readOnly: true
        updated-at:
          type: string
          format: date-time
          readOnly: true
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message
              field:
                type: string
                description: Field that caused the error
    AddressReference:
      type: object
      description: Reference to an address
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the address
        name:
          type: string
          description: Address name
        street1:
          type: string
          description: Street address line 1
        street2:
          type: string
          description: Street address line 2
        city:
          type: string
          description: City
        state:
          type: string
          description: State or province
        postal-code:
          type: string
          description: Postal or ZIP code
        country:
          type: object
          properties:
            id:
              type: integer
            code:
              type: string
              description: ISO 3166-1 alpha-2 country code
    DepartmentReference:
      type: object
      description: Reference to a department
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the department
        name:
          type: string
          description: Department name
    RequisitionCreate:
      type: object
      description: Schema for creating a new requisition
      required:
      - requisition-lines
      properties:
        req_title:
          type: string
          maxLength: 50
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        requester:
          $ref: '#/components/schemas/UserReference'
        requested-by:
          $ref: '#/components/schemas/UserReference'
        department:
          $ref: '#/components/schemas/DepartmentReference'
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          maxLength: 255
        need-by-date:
          type: string
          format: date-time
        justification:
          type: string
        buyer-note:
          type: string
        external-po-reference:
          type: string
          maxLength: 255
        hide-price:
          type: boolean
        pcard:
          type: object
          properties:
            id:
              type: integer
        requisition-lines:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RequisitionLine'
    RequisitionUpdate:
      type: object
      description: Schema for updating a requisition
      properties:
        req_title:
          type: string
          maxLength: 50
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        department:
          $ref: '#/components/schemas/DepartmentReference'
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          maxLength: 255
        need-by-date:
          type: string
          format: date-time
        justification:
          type: string
        buyer-note:
          type: string
        external-po-reference:
          type: string
          maxLength: 255
        hide-price:
          type: boolean
        requisition-lines:
          type: array
          items:
            $ref: '#/components/schemas/RequisitionLine'
        exported:
          type: boolean
  responses:
    UnprocessableEntity:
      description: Unprocessable entity - validation errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    limitParam:
      name: limit
      in: query
      description: Maximum number of records to return (max 50)
      schema:
        type: integer
        default: 50
        maximum: 50
    idParam:
      name: id
      in: path
      required: true
      description: Coupa internal unique identifier
      schema:
        type: integer
    offsetParam:
      name: offset
      in: query
      description: Number of records to skip for pagination
      schema:
        type: integer
        default: 0
    dirParam:
      name: dir
      in: query
      description: Sort direction (asc or desc)
      schema:
        type: string
        enum:
        - asc
        - desc
    returnObjectParam:
      name: return_object
      in: query
      description: Set to limited to return only key fields, or shallow to exclude nested objects
      schema:
        type: string
        enum:
        - limited
        - shallow
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication. Coupa supports the client_credentials grant type. Obtain client credentials from Coupa instance setup.
      flows:
        clientCredentials:
          tokenUrl: https://{instance}.coupahost.com/oauth2/token
          scopes:
            core.purchase_orders.read: Read purchase orders
            core.purchase_orders.write: Create and update purchase orders
            core.invoices.read: Read invoices
            core.invoices.write: Create and update invoices
            core.requisitions.read: Read requisitions
            core.requisitions.write: Create and update requisitions
            core.suppliers.read: Read suppliers
            core.suppliers.write: Create and update suppliers
    apiKey:
      type: apiKey
      in: header
      name: X-COUPA-API-KEY
      description: Legacy API key authentication. Coupa recommends migrating to OAuth 2.0. API keys are configured per Coupa instance.
externalDocs:
  description: Coupa Core API Documentation
  url: https://compass.coupa.com/en-us/products/product-documentation/integration-technical-documentation/coupa-core-api