openapi: 3.2.0 info: title: OpenGov Purchase Order Change Order API version: 1.0.0 description: API for managing purchase orders, line items, splits, and vendors. servers: - url: https://api-purchase-order.procurement.opengov.com description: Production - url: https://api-purchase-order.procurement.ogstaging.us description: Staging - url: https://api-purchase-order.procurement.ogintegration.us description: Integration security: - platformApiKey: [] - platformBearerToken: [] tags: - name: Change Order paths: /api/v1/po/entities/{entityId}/change-orders/search: post: tags: - Change Order operationId: changeOrder.searchChangeOrders parameters: - name: entityId in: path schema: type: string description: The UUID of the Platform entity default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1 format: uuid pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true description: The UUID of the Platform entity responses: '200': description: Success content: application/json: schema: type: object required: - data - meta properties: data: type: object required: - changeOrders properties: changeOrders: type: array items: type: object required: - id - entityId - poPurchaseOrderId - coNumber - coSequence - coDate - status - label - coReasonId - coReasonLabel - changeDescription - originalPoTotal - changeInTotal - revisedPoTotal - currency - poNumber - vendorName - fiscalYear - nonFinancialChanges - effectiveDate - revisedEndDate - createdBy - createdAt - updatedBy - updatedAt properties: id: type: number entityId: type: string poPurchaseOrderId: type: number coNumber: type: string coSequence: type: number coDate: type: string status: type: string label: anyOf: - type: string - type: 'null' coReasonId: anyOf: - type: number - type: 'null' coReasonLabel: anyOf: - type: string - type: 'null' changeDescription: anyOf: - type: string - type: 'null' originalPoTotal: type: string changeInTotal: type: string revisedPoTotal: type: string currency: type: string poNumber: type: string vendorName: anyOf: - type: string - type: 'null' fiscalYear: anyOf: - type: number - type: 'null' nonFinancialChanges: $id: /schemas/unknown title: unknown effectiveDate: anyOf: - type: string - type: 'null' revisedEndDate: anyOf: - type: string - type: 'null' createdBy: type: string createdAt: type: string updatedBy: type: string updatedAt: type: string additionalProperties: false additionalProperties: false meta: type: object required: - nextCursor - prevCursor - count properties: nextCursor: anyOf: - type: string - type: 'null' prevCursor: anyOf: - type: string - type: 'null' count: type: number additionalProperties: false additionalProperties: false '400': description: The request did not match the expected schema content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 400 code: type: string description: Machine-readable error code example: ValidationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: The request body failed validation. fieldErrors: type: array description: Per-field validation errors (present for 400 validation errors) items: type: object properties: parameter: type: string description: Dot-path to the field example: lineItems.0.lineItemSplits.1 detail: type: string description: Human-readable validation message example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00' code: type: string description: Machine-readable rule identifier example: BUDGET_INSUFFICIENT data: type: object description: Structured context for the error (account codes, amounts, IDs, etc.) additionalProperties: true example: accountNumber: 101-5100 accountPseudoKey: GF-101-5100 requestedAmount: 500 availableAmount: 200 required: - parameter - detail required: - status - code - detail '401': description: AuthError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 401 code: type: string description: Machine-readable error code example: AuthenticationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Authentication is required to access this resource. required: - status - code - detail '403': description: UnauthorizedError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 403 code: type: string description: Machine-readable error code example: AuthorizationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: You do not have permission to perform this action. required: - status - code - detail '404': description: EntityNotFoundError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 404 code: type: string description: Machine-readable error code example: PurchaseOrderNotFound detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Purchase order with id 123 was not found. required: - status - code - detail '500': description: InfrastructureError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 500 code: type: string description: Machine-readable error code example: InternalServerError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: An unexpected error occurred while processing your request. Please try again later. required: - status - code - detail description: 'Search change orders with optional filters: status, poNumber, searchTerm (coNumber/poNumber/vendorName). Cursor-based pagination. Applies reason nullification (BR-CR05) for Draft COs with deleted reasons.' summary: Search Change Orders requestBody: content: application/json: schema: type: object required: [] properties: status: type: array items: $ref: '#/components/schemas/CoStatus' poNumber: anyOf: - type: string - type: 'null' searchTerm: anyOf: - type: string - type: 'null' pagination: type: object required: [] properties: cursor: type: string pageSize: type: number additionalProperties: false additionalProperties: false required: true components: schemas: CoStatus: type: string enum: - Draft - PendingApproval - Approved - Cancelled description: 'Change order status: Draft, PendingApproval, Approved, Cancelled' title: CO Status securitySchemes: platformApiKey: description: OpenGov Platform API Key type: apiKey name: Authorization in: header platformBearerToken: type: http scheme: bearer