openapi: 3.1.0
info:
  title: Coupa Core Invoices Purchase Orders 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: Purchase Orders
  description: Create, retrieve, update, and manage purchase orders. Purchase orders represent commitments to buy goods or services from suppliers.
  externalDocs:
    url: https://compass.coupa.com/en-us/products/product-documentation/integration-technical-documentation/the-coupa-core-api/resources/transactional-resources/purchase-orders-api-(purchase_orders)
paths:
  /purchase_orders:
    get:
      operationId: listPurchaseOrders
      summary: Coupa List purchase orders
      description: Retrieve a list of purchase orders. Use query parameters to filter results. Coupa recommends always limiting result sets with GET criteria for optimal performance.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/returnObjectParam'
      - $ref: '#/components/parameters/dirParam'
      - name: status
        in: query
        description: Filter by order status. Includes buyer_hold, cancelled, closed, currency_hold, draft, error, expensed, issued, supplier_hold, supplier_window_hold, and exported.
        schema:
          type: string
          enum:
          - buyer_hold
          - cancelled
          - closed
          - currency_hold
          - draft
          - error
          - expensed
          - issued
          - supplier_hold
          - supplier_window_hold
          - exported
      - name: po-number
        in: query
        description: Filter by purchase order number
        schema:
          type: string
      - name: supplier[name]
        in: query
        description: Filter by supplier name
        schema:
          type: string
      - name: updated-at[gt]
        in: query
        description: Filter for records updated after this datetime
        schema:
          type: string
          format: date-time
      - name: created-at[gt]
        in: query
        description: Filter for records created 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 purchase orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseOrder'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createPurchaseOrder
      summary: Coupa Create a purchase order
      description: Create a new external purchase order. The type must be set to ExternalOrderHeader. A supplier and at least one order line are required.
      tags:
      - Purchase Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseOrderCreate'
          application/xml:
            schema:
              $ref: '#/components/schemas/PurchaseOrderCreate'
      responses:
        '201':
          description: Purchase order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /purchase_orders/{id}:
    get:
      operationId: getPurchaseOrder
      summary: Coupa Get a purchase order
      description: Retrieve a single purchase order by its Coupa internal ID.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/returnObjectParam'
      responses:
        '200':
          description: A single purchase order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updatePurchaseOrder
      summary: Coupa Update a purchase order
      description: Update an existing purchase order by its Coupa internal ID.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseOrderUpdate'
          application/xml:
            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'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /purchase_orders/{id}/cancel:
    put:
      operationId: cancelPurchaseOrder
      summary: Coupa Cancel a purchase order
      description: Cancel an existing purchase order.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Purchase order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /purchase_orders/{id}/close:
    put:
      operationId: closePurchaseOrder
      summary: Coupa Close a purchase order
      description: Close an existing purchase order.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Purchase order closed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /purchase_orders/{id}/issue:
    put:
      operationId: issuePurchaseOrder
      summary: Coupa Issue a purchase order
      description: Issue and send the purchase order to the supplier.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Purchase order issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /purchase_orders/{id}/reopen:
    put:
      operationId: reopenPurchaseOrder
      summary: Coupa Reopen a purchase order
      description: Reopen a soft-closed purchase order.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Purchase order reopened successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  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'
  schemas:
    PurchaseOrderCreate:
      type: object
      description: Schema for creating a new purchase order
      required:
      - type
      - supplier
      - currency
      - order-lines
      properties:
        type:
          type: string
          description: Must be ExternalOrderHeader for externally created orders
          enum:
          - ExternalOrderHeader
        po-number:
          type: string
          description: Purchase order number (auto-generated if not provided)
          maxLength: 20
        supplier:
          $ref: '#/components/schemas/SupplierReference'
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          maxLength: 255
        ship-to-user:
          $ref: '#/components/schemas/UserReference'
        payment-term:
          $ref: '#/components/schemas/PaymentTermReference'
        payment-method:
          type: string
          enum:
          - invoice
          - pcard
          - invoice_only
          - pcard_only
          - virtual_card
        shipping-term:
          $ref: '#/components/schemas/ShippingTermReference'
        order-lines:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderLine'
        hide-price:
          type: boolean
        transmission-method-override:
          type: string
          enum:
          - email
          - cxml
          - xml
          - do_not_transmit
        transmission-emails:
          type: string
    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
    ShippingTermReference:
      type: object
      description: Reference to a shipping term
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the shipping term
        code:
          type: string
          description: Shipping term code
    OrderLine:
      type: object
      description: A line item on a purchase order
      properties:
        id:
          type: integer
          description: Coupa unique identifier
          readOnly: true
        line-num:
          type: integer
          description: Line number
        description:
          type: string
          description: Item description
          maxLength: 255
        quantity:
          type: number
          format: decimal
          description: Quantity ordered
        price:
          type: number
          format: decimal
          description: Unit price
        total:
          type: number
          format: decimal
          description: Line total (quantity x price)
          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
          maxLength: 255
        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
        status:
          type: string
          description: Line status
          readOnly: true
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        supplier-aux-part-num:
          type: string
          description: Supplier auxiliary part number
        receiving-warehouse:
          type: object
          description: Receiving warehouse reference
          properties:
            id:
              type: integer
            name:
              type: string
        created-at:
          type: string
          format: date-time
          description: Timestamp when the line was created
          readOnly: true
        updated-at:
          type: string
          format: date-time
          description: Timestamp when the line was last updated
          readOnly: true
    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
    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
    PurchaseOrderUpdate:
      type: object
      description: Schema for updating a purchase order
      properties:
        po-number:
          type: string
          maxLength: 20
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          maxLength: 255
        ship-to-user:
          $ref: '#/components/schemas/UserReference'
        payment-term:
          $ref: '#/components/schemas/PaymentTermReference'
        payment-method:
          type: string
          enum:
          - invoice
          - pcard
          - invoice_only
          - pcard_only
          - virtual_card
        shipping-term:
          $ref: '#/components/schemas/ShippingTermReference'
        order-lines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
        hide-price:
          type: boolean
        transmission-method-override:
          type: string
          enum:
          - email
          - cxml
          - xml
          - do_not_transmit
        transmission-emails:
          type: string
        exported:
          type: boolean
    PurchaseOrder:
      type: object
      description: A purchase order representing a commitment to purchase goods or services from a supplier.
      properties:
        id:
          type: integer
          description: Coupa unique identifier
          readOnly: true
        po-number:
          type: string
          description: Purchase order number
          maxLength: 20
        status:
          type: string
          description: Current order status
          enum:
          - buyer_hold
          - cancelled
          - closed
          - currency_hold
          - draft
          - error
          - expensed
          - issued
          - supplier_hold
          - supplier_window_hold
          - exported
        type:
          type: string
          description: Order type (ExternalOrderHeader for externally created orders)
        version:
          type: integer
          description: PO supplier version number
        internal-revision:
          type: integer
          description: Internal revision number, increases each time a change is made
          readOnly: true
        change-type:
          type: string
          description: Last modification method
          enum:
          - change
          - revision
          - confirmation
        confirmation_status:
          type: string
          description: Current confirmation state
          enum:
          - pending_supplier_action
          - confirmed
          - partially_confirmed
          - rejected
        acknowledged-flag:
          type: boolean
          description: Whether the PO has been acknowledged by the supplier
        acknowledged-at:
          type: string
          format: date-time
          description: When the PO was acknowledged
        total:
          type: number
          format: decimal
          description: Total order amount
          readOnly: true
        currency:
          $ref: '#/components/schemas/CurrencyReference'
        supplier:
          $ref: '#/components/schemas/SupplierReference'
        supplier-site:
          type: object
          description: Supplier site reference
          properties:
            id:
              type: integer
            name:
              type: string
        requester:
          $ref: '#/components/schemas/UserReference'
        ship-to-address:
          $ref: '#/components/schemas/AddressReference'
        ship-to-attention:
          type: string
          description: Recipient contact name at the shipping address
          maxLength: 255
        ship-to-user:
          $ref: '#/components/schemas/UserReference'
        payment-term:
          $ref: '#/components/schemas/PaymentTermReference'
        payment-method:
          type: string
          description: Payment processing method
          enum:
          - invoice
          - pcard
          - invoice_only
          - pcard_only
          - virtual_card
        shipping-term:
          $ref: '#/components/schemas/ShippingTermReference'
        order-lines:
          type: array
          description: Collection of order line items
          items:
            $ref: '#/components/schemas/OrderLine'
        requisition-header:
          type: object
          description: Source requisition reference
          properties:
            id:
              type: integer
        invoice-stop:
          type: boolean
          description: Whether invoicing is blocked for this PO
        exported:
          type: boolean
          description: Whether the PO has been exported to an external system
        last-exported-at:
          type: string
          format: date-time
          description: When the PO was last exported
        hide-price:
          type: boolean
          description: Whether to hide pricing from the supplier
        price-hidden:
          type: boolean
          description: Whether pricing is hidden from the supplier
        transmission-method-override:
          type: string
          description: Override for the PO transmission method
          enum:
          - email
          - cxml
          - xml
          - do_not_transmit
        transmission-status:
          type: string
          description: Current transmission status
          enum:
          - sent_via_email
          - sent_via_cxml
          - sent_via_xml
          - pending
          - not_sent
        transmission-emails:
          type: string
          description: Comma-separated list of email addresses for PO transmission
        coupa-accelerate-status:
          type: string
          description: Status indicating whether the invoice has discount payment terms
        classification:
          type: string
          description: Order classification
          enum:
          - msp
          - supplier
          - vms
        confirm-by-hrs:
          type: integer
          description: Number of hours the supplier has to confirm the order
        order-confirmation-level:
          type: integer
          description: Confirmation depth indicator
        created-at:
          type: string
          format: date-time
          description: Timestamp when the PO was created
          readOnly: true
        updated-at:
          type: string
          format: date-time
          description: Timestamp when the PO was last updated
          readOnly: true
        created-by:
          $ref: '#/components/schemas/UserReference'
        updated-by:
          $ref: '#/components/schemas/UserReference'
    PaymentTermReference:
      type: object
      description: Reference to a payment term
      properties:
        id:
          type: integer
          description: Coupa unique identifier for the payment term
        code:
          type: string
          description: Payment term code
  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