Light v1 - Purchase Orders API

openapi: 3.2.0
info:
  title: Light v1 - Purchase Orders API
  version: 1.0.0
security:
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: v1 - Purchase Orders
paths:
  /v1/purchase-orders/{purchaseOrderId}/lines/bulk:
    put:
      tags:
      - v1 - Purchase Orders
      summary: Batch update purchase order lines
      description: Updates multiple purchase order line items
      operationId: batchUpdatePurchaseOrderLines
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ExternalBatchUpdatePurchaseOrderLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalPurchaseOrderLineV1Model'
    post:
      tags:
      - v1 - Purchase Orders
      summary: Bulk create purchase order lines
      description: Creates multiple purchase order line items
      operationId: bulkCreatePurchaseOrderLines
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ExternalCreatePurchaseOrderLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalPurchaseOrderLineV1Model'
  /v1/purchase-orders/{purchaseOrderId}/cancel:
    post:
      tags:
      - v1 - Purchase Orders
      summary: Cancel purchase order
      description: Cancels a purchase order
      operationId: cancelPurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
  /v1/purchase-orders/{purchaseOrderId}/close:
    post:
      tags:
      - v1 - Purchase Orders
      summary: Close purchase order
      description: Closes a purchase order
      operationId: closePurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
  /v1/purchase-orders:
    get:
      tags:
      - v1 - Purchase Orders
      summary: List purchase orders
      description: Returns a paginated list of purchase orders
      operationId: listPurchaseOrders
      parameters:
      - name: sort
        in: query
        schema:
          type: string
          description: "Sort string in the format `field:direction`. To provide multiple sort fields, separate them with commas.\n\nAvailable directions: `asc`, `desc`. \n\nAvailable fields: `purchaseOrderId`, `erpNumber`, `vendorName`, `ownerName`, `ownerId`, `companyEntityId`, `state`, `closedAt`, `cancelledAt`, `createdAt`, `totalAmount`."
          example: amount:desc,createdAt:asc
      - name: filter
        in: query
        schema:
          type: string
          description: "Filter string in the format `field:operator:value`. To provide multiple filters, separate them with commas.\n\nAvailable operators: `eq`, `ne`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`.\n - For `in` and `not_in` operators, provide multiple values separated by the pipe character (`|`). \n\nAvailable fields: `purchaseOrderId`, `vendorId`, `ownerId`, `state`, `erpNumber`, `updatedAt`."
          example: state:in:IN_DRAFT|SCHEDULED|PAID,amount:gte:500,vendorId:ne:null
      - name: limit
        in: query
        description: Maximum number of items to return. Default is 50, maximum is 200.
        schema:
          maximum: 200
          type: integer
          format: int32
      - name: offset
        in: query
        description: Number of items to skip before starting to collect the result set. Deprecated, use 'cursor' instead.
        deprecated: true
        schema:
          type: integer
          format: int64
      - name: cursor
        in: query
        description: 'The cursor position to start returning results from.

          To opt-in into cursor-based pagination, provide `0` for the initial request.

          For subsequent requests, use `nextCursor` and `prevCursor` from the previous response to navigate.

          Cursor values are opaque and should not be constructed manually.'
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPaginatedResponseV1ModelExternalBffPurchaseOrderV1Model'
    post:
      tags:
      - v1 - Purchase Orders
      summary: Create purchase order
      description: Creates a new purchase order
      operationId: createPurchaseOrder
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalCreatePurchaseOrderRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
  /v1/purchase-orders/{purchaseOrderId}/lines:
    post:
      tags:
      - v1 - Purchase Orders
      summary: Create purchase order line
      description: Creates a new purchase order line item
      operationId: createPurchaseOrderLine
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalCreatePurchaseOrderLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderLineV1Model'
  /v1/purchase-orders/{purchaseOrderId}:
    get:
      tags:
      - v1 - Purchase Orders
      summary: Get purchase order
      description: Returns a purchase order by ID
      operationId: getPurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
    patch:
      tags:
      - v1 - Purchase Orders
      summary: Update purchase order
      description: Updates an existing purchase order
      operationId: updatePurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalUpdatePurchaseOrderRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
  /v1/purchase-orders/{purchaseOrderId}/lock:
    post:
      tags:
      - v1 - Purchase Orders
      summary: Lock purchase order
      description: Locks a purchase order to prevent modifications
      operationId: locksPurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
  /v1/purchase-orders/{purchaseOrderId}/lines/{lineId}:
    delete:
      tags:
      - v1 - Purchase Orders
      summary: Delete purchase order line
      description: Deletes a purchase order line item
      operationId: deletePurchaseOrderLine
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: lineId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8: {}
    patch:
      tags:
      - v1 - Purchase Orders
      summary: Update purchase order line
      description: Updates a purchase order line item
      operationId: updatePurchaseOrderLine
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: lineId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalUpdatePurchaseOrderLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderLineV1Model'
  /v1/purchase-orders/{purchaseOrderId}/reset:
    post:
      tags:
      - v1 - Purchase Orders
      summary: Reset purchase order
      description: Resets a purchase order to its initial state
      operationId: resetPurchaseOrder
      parameters:
      - name: purchaseOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalPurchaseOrderV1Model'
components:
  schemas:
    ExternalCustomPropertyV1Model:
      type:
      - object
      - 'null'
      properties:
        groupId:
          type: string
          description: ID of the custom property group
          format: uuid
        groupInternalName:
          type: string
          description: Internal name of the custom property group
        values:
          type: array
          description: List of values. Note that this will be a single value unless the group input type supports multiple values
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyValueV1Model'
      description: Custom properties set on the vendor.
    ExternalUiClientExceptionErrorV1Model:
      type: object
      properties:
        type:
          type: string
          description: A string code identifying the error type
        message:
          type: string
          description: A human-readable message providing more details about the error
        path:
          type:
          - array
          - 'null'
          description: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
          items:
            type:
            - string
            - 'null'
            description: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
        context:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - object
            - 'null'
            description: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error
          description: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error
      description: List of errors providing details about what went wrong
    ExternalBffPurchaseOrderV1Model:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        createdBy:
          type:
          - string
          - 'null'
          format: uuid
        companyEntityId:
          type:
          - string
          - 'null'
          format: uuid
        purchaseRequestId:
          type:
          - string
          - 'null'
          format: uuid
        state:
          type: string
          description: ⚠️ This enum is not exhaustive; new values may be added in the future.
          enum:
          - IN_DRAFT
          - RESET_PENDING
          - APPROVED_ACCOUNTING_ENTRY_PENDING
          - OPEN
          - CLOSE_PENDING
          - CLOSED
          - CANCEL_PENDING
          - CANCELLED
        erpNumber:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
          example: USD
        totalAmount:
          type: integer
          format: int64
        totalNetAmount:
          type: integer
          format: int64
        totalTaxAmount:
          type: integer
          format: int64
        totalMatchedAmount:
          type: integer
          format: int64
        ownerId:
          type:
          - string
          - 'null'
          format: uuid
        ownerName:
          type:
          - string
          - 'null'
        vendorId:
          type:
          - string
          - 'null'
          format: uuid
        vendorEmail:
          type:
          - string
          - 'null'
        vendorName:
          type:
          - string
          - 'null'
        vendorAvatarUrl:
          type:
          - string
          - 'null'
        documentKey:
          type:
          - string
          - 'null'
        failureContext:
          $ref: '#/components/schemas/ExternalUiClientExceptionV1Model'
        purchaseOrderDate:
          type:
          - string
          - 'null'
          format: date
        deliveryAddress:
          type:
          - string
          - 'null'
        deliveryDate:
          type:
          - string
          - 'null'
          format: date
        erpSyncedAt:
          type:
          - string
          - 'null'
          format: date-time
        lockedAt:
          type:
          - string
          - 'null'
          format: date-time
        closedAt:
          type:
          - string
          - 'null'
          format: date-time
        cancelledAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lines:
          type: array
          items:
            $ref: '#/components/schemas/ExternalBffPurchaseOrderLineV1Model'
      description: List of records for the current page
    ExternalBatchUpdatePurchaseOrderLineRequestV1Model:
      type: object
      properties:
        lineId:
          type: string
          format: uuid
        description:
          type:
          - string
          - 'null'
        costCenterId:
          type:
          - string
          - 'null'
          format: uuid
        accountId:
          type:
          - string
          - 'null'
          format: uuid
        taxCodeId:
          type:
          - string
          - 'null'
          format: uuid
        quantity:
          type:
          - number
          - 'null'
        unitPrice:
          type:
          - integer
          - 'null'
          format: int64
        customProperties:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
    ExternalUiClientExceptionV1Model:
      type:
      - object
      - 'null'
      properties:
        name:
          type: string
          description: The error name
        type:
          type: string
          description: 'The error type


            ⚠️ This enum is not exhaustive; new values may be added in the future.'
          deprecated: false
          enum:
          - BAD_REQUEST
          - UNAUTHORIZED
          - FORBIDDEN
          - NOT_FOUND
          - CONFLICT
          - UNPROCESSABLE_CONTENT
        errors:
          type: array
          description: List of errors providing details about what went wrong
          items:
            $ref: '#/components/schemas/ExternalUiClientExceptionErrorV1Model'
      description: Failure context when vendor onboarding fails.
    ExternalBffPurchaseOrderLineV1Model:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        purchaseOrderId:
          type: string
          format: uuid
        description:
          type:
          - string
          - 'null'
        quantity:
          type:
          - integer
          - 'null'
          format: int64
        unitPrice:
          type:
          - integer
          - 'null'
          format: int64
        accountId:
          type:
          - string
          - 'null'
          format: uuid
        accountLabel:
          type:
          - string
          - 'null'
        taxCodeId:
          type:
          - string
          - 'null'
          format: uuid
        amount:
          type:
          - integer
          - 'null'
          format: int64
        taxAmount:
          type:
          - integer
          - 'null'
          format: int64
        netAmount:
          type:
          - integer
          - 'null'
          format: int64
        taxCodeLabel:
          type:
          - string
          - 'null'
        costCenterId:
          type:
          - string
          - 'null'
          format: uuid
        costCenterName:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ExternalPaginatedResponseV1ModelExternalBffPurchaseOrderV1Model:
      type: object
      properties:
        records:
          type: array
          description: List of records for the current page
          items:
            $ref: '#/components/schemas/ExternalBffPurchaseOrderV1Model'
        hasMore:
          type: boolean
          description: Boolean flag indicating if there are more records available
        total:
          type:
          - integer
          - 'null'
          description: Total number of records (only for offset pagination). This field is not guaranteed to be returned and only available for offset pagination, please do not rely on it and migrate to cursor pagination.
          format: int64
          deprecated: true
        nextCursor:
          type:
          - string
          - 'null'
          description: Cursor for fetching the next page (only for cursor pagination)
        prevCursor:
          type:
          - string
          - 'null'
          description: Cursor for fetching the previous page (only for cursor pagination)
    ExternalCustomPropertyValueV1Model:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
          format: uuid
        groupId:
          type: string
          description: ID of the custom property group
          format: uuid
        groupInternalName:
          type: string
          description: Internal name of the custom property group
        companyId:
          type: string
          description: ID of the company
          format: uuid
        internalName:
          type: string
          description: Internal name of the custom property value
        label:
          type: string
          description: Label of the custom property value
        context:
          type:
          - string
          - 'null'
          description: Context/description of the custom property value
        createdAt:
          type: string
          description: Timestamp when the custom property value was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp when the custom property value was last updated
          format: date-time
      description: List of values. Note that this will be a single value unless the group input type supports multiple values
    ExternalCreatePurchaseOrderLineRequestV1Model:
      type: object
      properties:
        description:
          type: string
        costCenterId:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        taxCodeId:
          type: string
          format: uuid
        quantity:
          type: number
        unitPrice:
          type: integer
          format: int64
        customProperties:
          type: array
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
    ExternalCreatePurchaseOrderRequestV1Model:
      type: object
      properties:
        vendorId:
          type:
          - string
          - 'null'
          format: uuid
        companyEntityId:
          type:
          - string
          - 'null'
          format: uuid
        ownerId:
          type:
          - string
          - 'null'
          format: uuid
        currency:
          type:
          - string
          - 'null'
          example: USD
        vendorEmail:
          type:
          - string
          - 'null'
        purchaseOrderDate:
          type:
          - string
          - 'null'
          format: date
        deliveryAddress:
          type:
          - string
          - 'null'
        deliveryDate:
          type:
          - string
          - 'null'
          format: date
        description:
          type:
          - string
          - 'null'
        lines:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCreatePurchaseOrderLineRequestV1Model'
        customProperties:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
    ExternalPurchaseOrderV1Model:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        createdBy:
          type: string
          format: uuid
        companyEntityId:
          type: string
          format: uuid
        purchaseRequestId:
          type: string
          format: uuid
        state:
          type: string
          description: ⚠️ This enum is not exhaustive; new values may be added in the future.
          enum:
          - IN_DRAFT
          - RESET_PENDING
          - APPROVED_ACCOUNTING_ENTRY_PENDING
          - OPEN
          - CLOSE_PENDING
          - CLOSED
          - CANCEL_PENDING
          - CANCELLED
        totalAmount:
          type: integer
          format: int64
        totalNetAmount:
          type: integer
          format: int64
        totalTaxAmount:
          type: integer
          format: int64
        erpNumber:
          type: string
        description:
          type: string
        currency:
          type: string
          example: USD
        ownerId:
          type: string
          format: uuid
        vendorId:
          type: string
          format: uuid
        vendorEmail:
          type: string
        deliveryAddress:
          type: string
        deliveryDate:
          type: string
          format: date
        documentKey:
          type: string
        failureContext:
          $ref: '#/components/schemas/ExternalUiClientExceptionV1Model'
        editStatus:
          type: string
          description: ⚠️ This enum is not exhaustive; new values may be added in the future.
          enum:
          - ALL_EDITS_ALLOWED
          - ALL_EDITS_LOCKED
        purchaseOrderDate:
          type: string
          format: date
        erpSyncedAt:
          type: string
          format: date-time
        lockedAt:
          type: string
          format: date-time
        closedAt:
          type: string
          format: date-time
        cancelledAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lines:
          type: array
          items:
            $ref: '#/components/schemas/ExternalPurchaseOrderLineV1Model'
        customProperties:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyV1Model'
    ExternalPurchaseOrderLineV1Model:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        purchaseOrderId:
          type: string
          format: uuid
        description:
          type: string
        costCenterId:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        taxCodeId:
          type: string
          format: uuid
        quantity:
          type: number
        unitPrice:
          type: integer
          format: int64
        amount:
          type: integer
          format: int64
        netAmount:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        customProperties:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyV1Model'
    ExternalUpdatePurchaseOrderLineRequestV1Model:
      type: object
      properties:
        customProperties:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
        description:
          type:
          - string
          - 'null'
        costCenterId:
          type:
          - string
          - 'null'
          format: uuid
        accountId:
          type:
          - string
          - 'null'
          format: uuid
        taxCodeId:
          type:
          - string
          - 'null'
          format: uuid
        quantity:
          type:
          - number
          - 'null'
        unitPrice:
          type:
          - integer
          - 'null'
          format: int64
    ExternalSetCustomPropertyRequestV1Model:
      type:
      - object
      - 'null'
      properties:
        groupId:
          type: string
          description: ID of the custom property group.
          format: uuid
        valueIds:
          type: array
          description: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
          items:
            type: string
            description: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
            format: uuid
        inlineValues:
          type:
          - array
          - 'null'
          description: Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.
          items:
            type:
            - string
            - 'null'
            description: Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.
      description: List of custom properties to set on the vendor. Replaces the existing set.
    ExternalUpdatePurchaseOrderRequestV1Model:
      type: object
      properties:
        customProperties:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
        vendorId:
          type:
          - string
          - 'null'
          format: uuid
        companyEntityId:
          type:
          - string
          - 'null'
          format: uuid
        ownerId:
          type:
          - string
          - 'null'
          format: uuid
        currency:
          type:
          - string
          - 'null'
          example: USD
        purchaseOrderDate:
          type:
          - string
          - 'null'
          format: date
        vendorEmail:
          type:
          - string
          - 'null'
        deliveryAddress:
          type:
          - string
          - 'null'
        deliveryDate:
          type:
          - string
          - 'null'
          format: date
        description:
          type:
          - string
          - 'null'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      description: Basic authentication header of the form **Basic** **<api_key>**, where **<api_key>** is your api key.
      name: Authorization
      in: header
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT